home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / s48.zip / USER-GUI.TXT < prev   
Lisp/Scheme  |  1992-07-03  |  16KB  |  482 lines
  1.  
  2.  
  3.     A line may take us hours, yet if it does not seem a moment's thought
  4.     All our stitching and unstitching has been as nought.
  5.  
  6.                             Yeats
  7.                             Adam's Curse
  8.  
  9.  
  10.  
  11. Random notes on the Scheme48 system.
  12.  
  13. -----
  14.  
  15. Introduction
  16.  
  17. Scheme48 is an implementation of the Scheme programming language as
  18. described in the Revised^4 Report on the Algorithmic Language Scheme.
  19. It is based on a compiler and interpreter for a virtual Scheme
  20. machine.  The name derives from our desire to have an implementation
  21. that is simple and lucid enough that it looks as if it were written in
  22. just 48 hours.  We don't claim to have reached that stage yet; much
  23. more simplification is necessary.
  24.  
  25. Scheme48 tries to be faithful to the Revised^4 Report, providing
  26. neither more nor less in the initial user environment.  (This is not
  27. to say that more isn't available in other environments; see below.)
  28. Support for numbers is weak: bignums are slow and floating point is
  29. nonexistent.  DEFINE-SYNTAX and SYNTAX-RULES are supported, but not
  30. the rest of the Revised^4 Scheme macro proposal.
  31.  
  32. Departing a bit from the Report, Scheme48 enforces one restriction
  33. from the IEEE 1178-1990 Scheme Standard: before being able to SET! a
  34. built-in variable like CONS or LOAD, you must DEFINE it first.
  35.  
  36. This is what might be called an alpha release.  Please report bugs,
  37. especially in the VM, especially core dumps, to
  38. scheme48-bugs@altdorf.ai.mit.edu.  It is a goal of this project to produce
  39. a bullet-proof system; we want no bugs and, especially, no crashes.
  40. (There are a few known bugs, listed in the TODO file that comes with
  41. the distribution.)
  42.  
  43. -----
  44.  
  45. Command line arguments
  46.  
  47.     s48 [-i image] [-h heapsize] [-a argument]
  48.  
  49. -i image
  50.     specifies a heap image file to resume (heap images are created by
  51.     the :dump and :build commands).  This defaults to a heap image
  52.     that runs a Scheme "command processor."
  53.  
  54. -h heapsize
  55.     specifies how much space should be reserved for allocation.
  56.     Heapsize is in bytes, and covers both semispaces for the copying
  57.     GC.  Cons cells are currently 12 bytes, so if you want to make
  58.     sure you can allocate a million cons cells, you should specify -h
  59.     24000000 (actually more than this, to account for the initial heap
  60.     image and breathing room).
  61.  
  62. -a argument
  63.     is only useful with images built using :build.  argument is passed
  64.     as a string to the procedure specified in the :build command.  E.g.
  65.  
  66.         > :build (lambda (a) (display a) (newline)) foo.image
  67.     > :exit
  68.     % scheme48vm -i foo.image -a mumble
  69.     mumble
  70.     % 
  71.  
  72. -----
  73.  
  74. Editing
  75.  
  76. We recommend running Scheme48 under emacs using "cmuscheme."  Can't
  77. tell you how to get emacs, but cmuscheme is available by anonymous ftp
  78. from ftp.cs.cornell.edu: pub/jar/cmu.tar.  Put these forms in your
  79. emacs init file:
  80.  
  81. (setq scheme-program-name "s48")  ;or whatever scheme48 is installed as
  82. (autoload 'run-scheme  "cmuscheme" "Run an inferior Scheme process." t)
  83.  
  84. You will probably also need to put the directory containing cmuscheme
  85. and related files in your emacs load-path:
  86.  
  87. (setq load-path (append load-path <directory>))
  88.  
  89. For futher documentation see cmuscheme.el and comint.el.
  90.  
  91. -----
  92.  
  93. Benchmark mode
  94.  
  95. If you want to run benchmarks, or just generally have your code run
  96. faster than it normally would, enter "benchmark mode" before loading
  97. anything.  Otherwise calls to primitives (like + and cons) won't be
  98. inlined, and programs will run more slowly.  Enter benchmark mode by
  99. issuing the :bench command to the command processor.
  100.  
  101. The system doesn't start in benchmark mode by default because the
  102. Scheme report permits redefinitions of built-in procedures.  In
  103. benchmark mode, such redefinitions don't work quite right, because
  104. previously compiled programs will use the byte codes for primitives
  105. instead of calling through variable's location.
  106.  
  107. -----
  108.  
  109. Inspector
  110.  
  111. There is a low-tech inspector, available via the :inspect and :debug
  112. commands.  The :inspect command starts an inspector command loop.
  113. There is a "current object", for which a menu of selectable components
  114. is displayed.  To inspect that component, just type the number.  For
  115. example:
  116.  
  117.     :inspect '(a (b c) d)
  118.     (a (b c) d)
  119.  
  120.     [0] a
  121.     [1] (b c)
  122.     [2] d
  123.     inspect: 1
  124.     (b c)
  125.  
  126.     [0] b
  127.     [1] c
  128.     inspect: 
  129.  
  130. Other inspector commands:
  131.     q       quit
  132.     u    pop object stack
  133.     d    down stack (current object must be a continuation)
  134.     m    print more of a long menu
  135.         dis     print a disassembly of current object (which must be a
  136.           closure, continuation, or template)
  137.     tem    go to a closure or continuation's template
  138.     (...)   evaluate a form
  139.  
  140. The inspector sets ## to be the object currently being inspected.
  141.  
  142. After an error occurs, :debug invokes the inspector on the
  143. continuation at the point of the error.  The U and D (up and down)
  144. commands then make the inspector look like a conventional stack
  145. debugger, with continuationspalying the role of stack frames.  D goes
  146. to older or deeper continuations (frames), and U goes back up to more
  147. recent ones.
  148.  
  149. -----
  150.  
  151. Disassembler
  152.  
  153. The :dis command disassembles procedures.  Also available as the "dis"
  154. command in the inspector.
  155.  
  156.     > :dis cons
  157.     (lap cons
  158.        0  (check-nargs= 2)
  159.        2  (make-env 2)
  160.        4  (local 0 2)
  161.        7  (push)
  162.        8  (local 0 1)
  163.       11  (cons)
  164.       12  (return))
  165.     > 
  166.  
  167. The disassembler can also be invoked on continuations and templates.
  168. Templates are the static components of procedures; these are found
  169. inside of procedures and continuations, and look like vectors that
  170. have code vectors as their zeroth component.
  171.  
  172. -----
  173.  
  174. Package system
  175.  
  176. [Jun 1992: I bit the bullet and wrote a little module system for
  177. scheme48.  Tried to make it as concise and featureless as possible.
  178. To avoid confusion with Scheme Xerox's module system I have called it
  179. a "package" system (which KMP won't like one bit).  Here's a brief
  180. description in very operational terms.  I won't say it's useable in
  181. this form -- a few other things might be required, like some kind of
  182. :load-package command that exploits an association between packages
  183. and files.  And the implementation is bound to be buggy, especially in
  184. the realm of forward reference adjustments (retroactive shadwoing and
  185. exports).  Comments welcome.  -Jonathan]
  186.  
  187. The package system is superficially like the Common Lisp package
  188. system, except that it controls the mapping of names to denotations
  189. instead of the mapping of string to symbols.  (A name is represented
  190. internally as a symbol; a denotation is either a variable location,
  191. syntactic operator, or a package.)  Packages, like macros, are
  192. second-class.  They are created with the DEFINE-PACKAGE special form,
  193. and accessed in one of two ways: by the PACKAGE-REF special form, or
  194. by being "opened" in a DEFINE-PACKAGE.
  195.  
  196. DEFINE-PACKAGE works like this:
  197.  
  198.     <definition> ::= (define-package <name> <clause> ...)
  199.  
  200. where
  201.  
  202.     <clause> ::= (access <name> ...)
  203.            | (open <name> ...)
  204.            | (export <name> ...)
  205.            | (file <name> ...)
  206.  
  207. An OPEN clause specifies which packages will be opened up for use
  208. inside the new package (like USE-PACKAGE in Common Lisp).  At least
  209. one package must be specified or else it will be impossible to write
  210. any useful programs inside the package, since DEFINE, LAMBDA, CONS,
  211. PACKAGE-REF, etc. will be unavailable.  Typical packages to list in
  212. the OPEN clause are SCHEME (which exports Revised^4 Scheme) and
  213. DEFPACKAGE (which exports PACKAGE-REF and DEFINE-PACKAGE).  There are
  214. some other initial packages as well; see below.
  215.  
  216. An ACCESS clause specifies which package names will be carried into
  217. the package.  This allows use of a package via PACKAGE-REF or
  218. DEFPACKAGE without opening up the package.  If a package name isn't
  219. listed in an OPEN or ACCESS clause, and is not defined internal to a new
  220. package via another DEFINE-PACKAGE, then that package will not be
  221. valid in a PACKAGE-REF or DEFINE-PACKAGE.  If a package ACCESSes any
  222. other packages, it should probably also OPEN the DEFPACKAGE package so
  223. that PACKAGE-REF itself is available.
  224.  
  225. An EXPORT clause specifies names that are to be defined in this
  226. package and made accessible outside of the package (via another OPEN or
  227. ACCESS and PACKAGE-REF).
  228.  
  229. FILE clauses are currently ignored.
  230.  
  231. PACKAGE-REF has the following syntax:
  232.  
  233.     <expression> ::= (package-ref <name1> <name2>)
  234.  
  235. <name1> must be the name of a package, and <name2> must be something
  236. that the package exports.
  237.  
  238. An imported binding may be lexically overridden or "shadowed" simply
  239. by doing a DEFINE (or DEFINE-SYNTAX or DEFINE-PACKAGE) of the name
  240. whose binding is to be shadowed.  This will create a new binding
  241. without having any effect on the binding in the opened package.  For
  242. example, in the USER package one can do (DEFINE CAR 'CHEVY) without
  243. affecting the binding of the name CAR in the SCHEME package.
  244.  
  245. It is an error to assign (SET!) a variable except in the package that
  246. defines it.  (Unfortunately, the implementation doesn't currently
  247. enforce this restriction.  The restriction is necessary in order to
  248. make module compilation, also currently unimplemented, semantically
  249. sound.)
  250.  
  251. The command processor supports the package system with several special
  252. commands.  For these commands, package names are resolved in a package
  253. called the PACKAGES package.
  254.  
  255. - :set-package package-name  moves the command processor inside a
  256.   specified package.  E.g.
  257.     :set-package user
  258.   moves into the user initial package (which is the binding of the
  259.   name USER in the PACKAGES package).
  260.   The command processor displays the name of the current package in
  261.   the prompt, unless the current package is the user package.
  262.  
  263. - The :load-into command loads one or more files into a specified
  264.   package.
  265.         :load-into package file1 file2 ...
  266.   is similar to :set-package package followed by :load file1 file2
  267.   ..., except that the current package ends up being unchanged.
  268.  
  269. - The :new-package command creates a new package.
  270.     :new-package name open1 open2 ...
  271.   is short for the sequence
  272.     > :set-package packages
  273.     packages> (define-package name (open open1 open2 ... scheme))
  274.     packages> :set-package name
  275.     name> 
  276.  
  277. - :export name1 name2 ...  causes the indicated names to be exported
  278.   from the current package, as if they had been listed in the EXPORT
  279.   clause of the DEFINE-PACKAGE form that created the current package.
  280.  
  281. - :open-package name1 name2 ...
  282.  
  283. - :clear-package name  undoes any definitions that have been made in
  284.   the indicated package.
  285.  
  286. [There probably also ought to be a :access command.]
  287.  
  288. Predefined packages: the following are initially defined (in the
  289. PACKAGES package):
  290.  
  291.     scheme  -- exports Revised^4 Scheme: LAMBDA, QUOTE, CONS, etc.
  292.     user  -- the user initial package (command processor indicates
  293.         that this is current with a simple "> " prompt).  This doesn't
  294.     export any bindings, so it doesn't make sense to OPEN or ACCESS
  295.     it, only to :load-into or :set-package to it.  Opens only the
  296.     scheme package.
  297.     :disable is the same as :set-package user.
  298.     defpackage  -- exports DEFINE-PACKAGE, PACKAGE-REF, SCHEME, and
  299.         DEFPACKAGE.
  300.     table  -- hash tables
  301.     record  -- record types
  302.     enumerated  -- enumerated types
  303.     packages  -- opens scheme and defpackage; no exports.
  304.     primitives  -- exports Scheme48 virtual machine primitives.
  305.         See rts/reflect.scm for a list.  Some of these primitives do
  306.     no error checking, and improper use may crash the system.
  307.     The primitives package doesn't export things like
  308.     CAR that are already exported by the SCHEME package (this may
  309.     be a design error?  may change).
  310.     system  -- exports all kinds of stuff; highly unstable.  See
  311.         rts/reflect.scm for a list.
  312.     :enable is the same as :set-package system.
  313.     for-syntax  -- the package in which <expression> in
  314.         (define-syntax <name> <expression>) is evaluated.
  315.     No exports.
  316.  
  317. -----
  318.  
  319. LOAD
  320.  
  321. The load procedure exported by the scheme package takes an optional
  322. second argument that, if supplied, should be the package into which
  323. the file named by its first argument should be loaded.  If not
  324. supplied, load loads the file into the package that is the current
  325. value of (fluid $package-for-load).  Packages may be obtained for this
  326. purpose as first-class Scheme values by using the get-package
  327. procedure, which looks up a package name in the packages package.
  328. fluid, $package-for-load, and get-package are all exported by the
  329. system package.
  330.  
  331. Whether the package argument is supplied or not, load binds (using
  332. let-fluid) $package-for-load to the package into which the file is
  333. loaded.  $package-for-load is also set (using set-fluid!) by the
  334. command processor's :set-package and :new-package commands.
  335.  
  336. -----
  337.  
  338. access-scheme48
  339.  
  340. A simpler way to get at features that are ordinarily hidden inside the
  341. the system or primitives packages is the "access-scheme48" procedure,
  342. which is exported by the scheme package.  (access-scheme48 'name) is
  343. similar to (package-ref system name), except that name need not be
  344. exported by the system package.  E.g.
  345.  
  346.     (define make-fluid (access-scheme48 'make-fluid))
  347.     (define fluid (access-scheme48 'fluid))
  348.  
  349. will copy the values of the variables make-fluid and fluid to the user
  350. package.  But it's better style to use the package system; run any
  351. program requiring these bindings in a package that uses the defpackage
  352. package and accesses the system package.
  353.  
  354. -----
  355.  
  356. Library
  357.  
  358. There are some useful libraries in the "misc" subdirectory of the
  359. distribution.  Before using many of these it is necessary to load the
  360. appropriate package definitions:
  361.  
  362.     > :load-into packages misc/package-defs.scm
  363.  
  364. pp.scm
  365.     A pretty-printer.  (p <exp>) will pretty-print the result of <exp>,
  366.     which must be an S-expression.  (Source code for procedures is not
  367.     retained or reconstructed.)
  368.  
  369.     The procedure pretty-print takes three arguments: the object to be
  370.     printed, a port to write to, and the current horizontal cursor
  371.     position.  If you've just done a newline, then pass in zero for
  372.     the position argument.
  373.  
  374.     The algorithm is very peculiar, and sometimes buggy.
  375.  
  376.     > :load-into pp misc/pp.scm
  377.     > :open-package pp
  378.  
  379. random.scm
  380.     Random number generator.
  381.  
  382.     > :load-into random misc/random.scm
  383.     > :open-package random
  384.         > (define random (make-random <seed>))
  385.     > (random)  =>  a pseudo-random number between 0 and 2^28
  386.  
  387.  
  388. sort.scm
  389.     Online merge sort (see comment at top of file)
  390.  
  391.         (sort-list <list> <pred>)
  392.     (sort-list! <list> <pred>)
  393.  
  394. tokenize.scm
  395.     Defines lexical utilities (something like "read tables" in Common
  396.     Lisp).
  397.  
  398. pratt.scm
  399.     An infix parser shell (courtesy Paradigm Associates, Inc.).  Needs
  400.     tokenize.scm.
  401.  
  402. sgol.scm
  403.     An example use of pratt.scm.  See top of file for description.
  404.  
  405. sicp.scm
  406.     Compatibility for "Structure & Interpretation of Computer Programs."
  407.     Just load it into the user package.
  408.  
  409. queue.scm
  410.     FIFO queues.
  411.  
  412. defrecord.scm
  413.     A define-record-type macro, providing more concise use of the
  414.     record package.
  415.  
  416. format.scm
  417.     A simple FORMAT procedure, similar to Common Lisp's or T's.
  418.  
  419. receive.scm
  420.     Multiple value returns.
  421.  
  422. bigbit.scm
  423.     Extensions to the bitwise logical operators (exported by
  424.     the primitives package) so that they operate on bignums.
  425.  
  426.     > :load-into system bigbit.scm
  427.  
  428. xport.scm, new-ports.scm
  429.     Ports for reading from and writing to strings, and related things.
  430.     Documentation pending.
  431.  
  432. assem.scm
  433.     An assembler for the virtual machine.
  434.  
  435.     > :load-into system misc/assem.scm
  436.     > :open-package assembler
  437.     > ((%lap foo (literal '1) (return)))
  438.     1
  439.  
  440. thread.scm
  441.     A multitasking subsystem.  Needs queue.scm, compose-cont.scm, and
  442.     bindings from the system and primitives packages.
  443.  
  444.     > :load-into queue misc/queue.scm
  445.     misc/queue.scm ..................
  446.     > :load-into thread misc/compose-cont.scm misc/thread.scm
  447.     misc/compose-cont.scm ..
  448.     misc/thread.scm ...............................................
  449.     > :open-package thread
  450.     > (start-multitasking (simple-thread-condition-handler))
  451.     0
  452.     > (define (foo) (display "hi") (newline) (relinquish-timeslice) (foo))
  453.     > (define th (spawn foo 'foo))
  454.     hi
  455.     > 12
  456.     hi
  457.     12
  458.     > (kill-thread th)
  459.     hi
  460.     #t
  461.     > 
  462.  
  463.     Task switching is preemptive, except that input (read-char) is not
  464.     interrupted.
  465.  
  466. compose-cont.scm
  467.     Hack needed for threads package.
  468.  
  469. sleep.scm
  470.     A SLEEP procedure, to be used with the threads package.
  471.  
  472.     > :load-into thread misc/sleep.scm
  473.  
  474.     This will busy-wait if there's nothing else to do, so it's not
  475.     advisable under time-sharing.
  476.  
  477. -----
  478.  
  479. Acknowledgment
  480.  
  481. Thanks to Deborah Tatar for providing the Yeats quotation.
  482.